Рекомендации по конвертации markvan в html

html

— язык разметки текста для веб-страниц в сети Интернет. Html размечает не только сам текст (произведение автора), но и его окружение (регионы, блоки, меню). В то же время markvan предназначен исключительно для произведения и имеет несколько иное видение разметки текста. Таким образом возможности html только частично пересекаются с возможностями разметки маркван, что может вызвать небольшие (преодолимые) сложности при конвертации.

В изложении данной статьи предполагается, что читатель уже знаком с html.

При написании собственного конвертера вы можете использовать иные hmtl-теги, главное, чтобы не терялся смысл изложения.

Это частичное и может быть несоответствующее руководство, т.к. прорамма дорабатывается и вносятся изменения.

Базовая разметка

Разбиение на части

В маркване 3 группы заголовков: название, части и главы, текстовые заголовки от 1 до 6. Причем, части и главы могут не использоваться.

В html заголовки h1-h6 должны применяться последовательно,поэтому при конвертации придётся отслеживать какие заголовки встречаются в данном тексте и перенумеровывать их в по порядку. К заголовкам добавляются классы с наименованием как это принято в маркване, чтобы можно было применить присущие им стили.

Классы для заголовков

"***": "title",
"^^^": "part",
'"""': "chapter",
"===": "th1",
"---": "th2",
"...": "th3",
",,,": "th4",
":::": "th5",
";;;": "th6",
"~~~": "th-empty",

Название это всегда тег h1. Далее, нам встречается текстовый заголовок. Если частей и глав в произведении нет, то заголовок конвертируем в тег h2 и добавляем класс th1. Пример:

***
Инструкция по оказанию первой помощи


===
1. Общие требования охраны труда

1.1. Первая медицинская помощь представляет собой комплекс срочных мероприятий,
проводимых при несчастных случаях и внезапных заболеваниях, направленных на
прекращение действия повреждающего фактора, на устранение явлений, угрожающих жизни,
на облегчение страданий и подготовку пострадавшего к отправке в лечебное учреждение.
<...>

<h1 class="title">Инструкция по оказанию первой помощи</h1>
	<h2 class="th1">1. Общие требования охраны труда</h2>
		<p>1.1. Первая медицинская помощь представляет собой комплекс срочных мероприятий, проводимых при несчастных случаях и внезапных заболеваниях, направленных на прекращение действия повреждающего фактора, на устранение явлений, угрожающих жизни, на облегчение страданий и подготовку пострадавшего к отправке в лечебное учреждение. &lsaquo;&hellip;&rsaquo;</p>

Ещё нам могут встречаться составные названия частей, глав и текстовых заголовков первого уровня с идентификатором. Добавляем класс для идентификатора.

Более сложный пример:

***
Тысячеликий герой



"""
Предисловие

Истины, содержащиеся в религиозных учениях, в конечном счёте так искажены и систематически замаскированы под что-то иное, ‹…›



"""
Пролог
Мономиф


===
1. Миф и сновидение

Когда мы высокомерно наблюдаем за красноглазым шаманом из Конго в разгар ритуала или получаем изысканное наслаждение от чтения утонченных переводов загадочных стихов Лао Цзы; ‹…›




^^^
ЧАСТЬ I
Приключения героев



"""
Глава I
Начало пути


===
1. Зов странствий

Давным давно, когда люди желали и воплощали свои желания в жизнь, жил один царь, все дочери которого были красавицы, но самая младшая была так прекрасна, что само солнце, которое столько всего повидало на свете дивилось её красотой каждый раз, когда касалась лучами её лица. ‹…›

<h1 class="title">Тысячеликий герой</h1>
		<h3 class="chapter">Предисловие</h3>
			<p>Истины, содержащиеся в религиозных учениях, в конечном счёте так искажены и систематически замаскированы под что-то иное, — пишет фрейд, — &lsaquo;&hellip;&rsaquo;<p>
		<h3 class="chapter">Пролог<br>Мономиф</h3>
			<h4 class="th1">1. Миф и сновидение</h4>
				<p>Когда мы высокомерно наблюдаем за красноглазым шаманом из Конго в разгар ритуала или получаем изысканное наслождение от чтения утонченных переводов загадочных стихов Лао Цзы; &lsaquo;&hellip;&rsaquo;</p>

	<h2 class="part">ЧАСТЬ I<br>Приключения героев</h2>
		<h3 class="chapter">Глава I</br>Начало пути</h3>
			<h4 class="th1">1. Зов странствий</h4>
				<p>Давным давно, когда люди желали и воплощали свои желания в жизнь, жил один царь, все дочери которого были красавицы, но самая младшая была так прекрасна, что само солнце, которое столько всего повидало на свете дивилось её красотой каждый раз, когда касалась лучами её лица. &lsaquo;&hellip;&rsaquo;</p>

[(

Тысячеликий герой

Предисловие

Истины, содержащиеся в религиозных учениях, в конечном счёте так искажены и систематически замаскированы под что-то иное, ‹…›

Пролог

Мономиф

1. Миф и сновидение

Когда мы высокомерно наблюдаем за красноглазым шаманом из Конго в разгар ритуала или получаем изысканное наслаждение от чтения утонченных переводов загадочных стихов Лао Цзы; ‹…›

ЧАСТЬ I

Приключения героев

Глава I

Начало пути

1. Зов странствий

Давным давно, когда люди желали и воплощали свои желания в жизнь, жил один царь, все дочери которого были красавицы, но самая младшая была так прекрасна, что само солнце, которое столько всего повидало на свете дивилось её красотой каждый раз, когда касалась лучами её лица. ‹…›

Выделения текста

я таблица

Включения в повествование

Блок конвертируется в <figure> с соответствующим классом. Можно смотреть на примере этого сайта

я таблица

Текстовое включение

[( #1 Пример текстового включения
Он проснулся в темноте; проснулся сразу, легко, не сделав ни одного движения, — просто открыл глаза и увидел что ещё темно.
)]

Html код включения

<figure class="inclusion text norm" id="1">
	<figcaption>Пример текстового включения</figcaption>
	<text class="incl-body">
		<p class="incl">Он проснулся в темноте; проснулся сразу, легко, не сделав ни одного движения, — просто открыл глаза и увидел что ещё темно.</p>
	</text>
</figure>

Вот так оно выглядит в браузере:

Пример текстового включения

Он проснулся в темноте; проснулся сразу, легко, не сделав ни одного движения, — просто открыл глаза и увидел что ещё темно.

Стихи

В стихах параграфы разделяются не по строкам (в конце ставится тег <br>), а по пустым строкам.

Последняя строка отделенная пробелом и содержащая цифры помечается классом date.

[(poem
Михаил Лермонтов
***
Парус (Белеет парус одинокий)

Белеет парус одинокой
В тумане моря голубом!..
Что ищет он в стране далекой?
Что кинул он в краю родном?..

Играют волны — ветер свищет,
И мачта гнется и скрыпит…
Увы! он счастия не ищет
И не от счастия бежит!

<..>
‹…›

1832 г.
)]

<figure class="text poem">
	<figcaption>
		Михаил Лермонтов
	</figcaption>
	<text>
		<!--<p class="author">Михаил Лермонтов</p>-->
		<h1>Парус</h1>
		<stanza>Белеет парус одинокой<br>
			В&nbsp;тумане моря голубом!..<br>
			Что ищет он&nbsp;в&nbsp;стране далекой?<br>
			Что кинул он&nbsp;в&nbsp;краю родном?..</stanza>
		<p>Играют волны&nbsp;— ветер свищет,<br>
			И&nbsp;мачта гнется и&nbsp;скрыпит…<br>
			Увы! он&nbsp;счастия не&nbsp;ищет<br>
			И&nbsp;не&nbsp;от&nbsp;счастия бежит!</p>
		<p>‹…›</p>
		<p class="date">1832&nbsp;г.</p>
	</text>
</figure>

также были предложения строчки делать не тегом <p>, а <poem><stanza><line>

Цитата

не утверждено. здесь figure и нужно ли выделять ссылку

Блок с цитатой имеет серьезные отличия. Заголовок включения в цитатах не нужен.

Майкл Джордан

«Я могу смириться с неудачей. ‹…› Но я не могу смириться с тем, что не попробовал»

<div class="inclusion text">
	<text class="body quote">
		<blockquote>
			<p>«Я могу смириться с неудачей. ‹…› Но я не могу смириться с тем, что не попробовал»</p>
		</blockquote>
		<p> <span class="author">Майкл Джордан</span>, <span>баскетболист</span></p>
		<cite>Какой-то сайт в Интернете</cite>
	</text>
</div>

Изображения

Пример простого изображения без названия и описания включения:

<img src="konvertatsija/img/shema_zvetka.png" alt="Схема строения цветка">

В случает добавления названия или описания включения, используем тег figure:

<figure class="media">
	<img src="konvertatsija/img/shema_zvetka.png" alt="Схема строения цветка">
	<figcaption>
		<h4>Схема строения цветка</h4>
		<small>1 — цветоножка; 2 — прицветник; 3 — цветоложе; 4 — подчашка; 5 чашечка; 6 — венчик; 7 — тычиночные нити; 8 — пыльник тычинки; 9 — пыльца; 10 — рыльце пестика; 11 — столбик пестика; 12 — завязь пестика; 13 семязачаток</small>
	</figcaption>
</figure>

Преформатированный текст

[= Пример преформатированного текста
(ㆆ_ㆆ)
=]

Пример преформатированного текста

(ㆆ_ㆆ)

Формулы

Формулы можно записывать с помощью AsciiMath, TeX или MathML. AsciiMath и TeX экспортируются в html как есть, и в браузере обрабатываются яваскриптом. Либо (в будущем) можно их конвертировать в MathML на сервере.

[%asc
S = pi*r^2
%]

S = pi*r^2

[%math Пример. Формула в MathML
<mrow>
	<mi>S</mi>
	<mo>=</mo>
	<mi>π</mi>
	<mo>*</mo>
	<msup>
		<mi>r</mi>
		<mn>2</mn>
	</msup>
</mrow>
%]

<div class="inclusion formula">
	<div class="title">Пример. Формула в MathML</div>
	<math class="body" xmlns="http://www.w3.org/1998/Math/MathML">
		<mrow>
			<mi>S</mi>
			<mo>=</mo>
			<mi>π</mi>
			<mo>*</mo>
			<msup>
				<mi>r</mi>
				<mn>2</mn>
			</msup>
		</mrow>
	</math>
</div>

Код

[&pascal #235 Пример 235. Условное выражение
if x > 0 {a = a + b}
&]

<div id="235" class="inclusion code">
	<div class="title">Пример 235. Условное выражение</div>
	<code class="body pascal">if x &gt; 0 {a = a + b}</code>
</div>

Фрагменты кода

<figcaption>Пример 235. Условное выражение</figcaption>

</figure>

Таблицы

Маркван позволяет создавать нормальные таблицы, если нужно что-то нестандартное, то вы можете сверстать прямо в html.

Название таблицы в <caption>

Всё, что выше линии из дефисов --- это шапка таблицы <thead> остальное в <tbody> до линии из символов равно === а остальное это <tfoot>.

Столбцы, к которым нужно привлечь внимание читателя, можно пометить !, соответственно <col class="advise">

Столбцы, которые необходимо выровнять по правому краю отмечаются знаком больше > или # (больше пересекается с результатом), соответственно в ячейках class="end"

[| Таблица 1. Покупки.*
| Товар
		| Цена, руб
				:!
						|# Количество
								|\ Сумма, руб
:
		|> опт
				|> розница
						:
								:
----------------------------------------------
| Тетрадь ученическая в клеточку Арт 342135
		| 90
				| 100
						| 2
								| 200
| Карандаш простой H2 Koh-i-noor Арт 675631
		| 8.5
				| 10
						| 4
								| 40
==============================================
| Итого:
		.
				.
						.
								| 240
|]
|* Демонстрационная таблица

<table>
	<caption>Таблица 1. Покупки.</caption>
	<colgroup>
		<col>
		<col>
		<col class="adwise">
		<col>
		<col>
	</colgroup>
	<thead>
		<tr>
			<th rowspan="2">Товар</th>
			<th colspan="2">Цена, руб</th>
			<!-- none th -->
			<th rowspan="2">Количество</th>
			<th rowspan="2">Сумма, руб</th>
		</tr>
		<tr>
			<!-- none th -->
			<th>опт</th>
			<th>розница</th>
			<!-- none th -->
			<!-- none th -->
		</tr>
	</thead>
	<tbody>
		<tr>
			<td>Тетрадь ученическая в клеточку Арт 342135</td>
			<td class="end">90</td>
			<td class="end">100</td>
			<td class="end">2</td>
			<td class="end">200</td>
		</tr>
		<tr>
			<td>Карандаш простой H2 Koh-i-noor Арт 675631
				<br>(дополнительное описание)
			</td>
			<td class="end">8.5</td>
			<td class="end">10</td>
			<td class="end">4</td>
			<td class="end">40</td>
		</tr>
	</tbody>
	<tfoot>
		<tr>
			<td colspan="4">Итого:</td>
			<!-- none td -->
			<!-- none td -->
			<!-- none td -->
			<td class="end">240</td>
		</tr>
	</tfoot>
</table>

Медиа

<object
  type="video/mp4"
  data="https://www.youtube.com/watch?v=Sp9ZfSvpf7A"
  width="1280"
  height="720"></object>

Сноски

Текст в markva

Двести лет назад в Калининграде^* было семь мостов, соединяющих берега реки Прегель^**.

^* В те времена он назывался Кенигсберг.

^** Ныне Прего́ля.

Сноска имеет идентификатор ftn-lnk-* (для того, чтобы из текста сноски можно было вернуться обратно) и ссылку на содержание сноски ftn-txt-*.

Тексты сносок так же имеет id и ссылку на место откуда на них ссылались.

Html код

<p>Двести лет назад в Калининграде<sup id="ftn-lnk-*"><a href="#ftn-txt-*">*</a></sup> было семь мостов, соединяющих берега реки Прегель.<sup><a id="ftn-lnk-**" href="#ftn-txt-**">**</a></sup></p>
<--! Текст сноски, расположенный далее по тексту -->
<div class="footnotes">
	<hr class="ftn">
	<p id="ftn-txt-*"><sup><a href="#ftn-lnk-*">*</a></sup><span>В те времена он назывался Кенигсберг.</span></p>
	<p id="ftn-txt-**"><sup><a href="#ftn-lnk-**">**</a></sup><span>Ныне Прего́ля.</span></p>
</div>

Результат в браузере

Двести лет назад в Калининграде^* было семь мостов, соединяющих берега реки Прегель^**.

^* В те времена он назывался Кенигсберг.

^** Ныне Прего́ля.

С помощью яваскрипта можно показывать содержание сноски при наведении на идентификатор.

Это для оглавления

Html код

<p>Двести лет назад в Калининграде<sup><a id="ftn-1" href="#text-ftn-1">2</a></sup> было семь мостов, соединяющих берега реки Прегель.</p>
<div  class="footnotes">
	<sup><a href="#ftn-1">1</a></sup><span id="text-ftn-1">В те времена он назывался Кенигсберг.</span>
</div>

Результат в браузере

Двести лет назад в Калининграде^* было семь мостов, соединяющих берега реки Прегель.

^* В те времена он назывался Кенигсберг.

Ссылки

Я рекомендую вам прочитать книгу ~[«Ещё один великолепный МИФ»]~ ~[Роберта Асприна]~.
|~ https://ru.wikipedia.org/wiki/Ещё_один_великолепный_МИФ (Упоминание в Википедии книги "Ещё один великолепный МИФ")
|~ https://ru.wikipedia.org/wiki/Асприн,_Роберт_Линн (Асприн, Роберт Линн - Википедия об авторе)

htm

Я рекомендую вам прочитать книгу <a href="https://ru.wikipedia.org/wiki/Ещё_один_великолепный_МИФ" title="Упоминание в Википедии книги "Ещё один великолепный МИФ">«Ещё один великолепный МИФ»</a> <a href="https://ru.wikipedia.org/wiki/Асприн,_Роберт_Линн" title="Асприн, Роберт Линн - Википедия об авторе">Роберта Асприна</a>.

~ http://example.com/Twenty_Years_After--Dumas_Alexandre (Купить книгу "Двадцать лет спустя")

<a href="http://example.com/Twenty_Years_After--Dumas_Alexandre" title="Купить книгу "Двадцать лет спустя"">
<img src="/img/duma20_cover.jpg">
</a>

В HTML существует несколько тегов для обозначения цитат:

<blockquote> предназначен для выделения длинных цитат, которые могут состоять из нескольких абзацев. Тег выделяет цитату как отдельный блок текста с отступами.

<q> предназначен для выделения коротких цитат в предложениях. Текст внутри этого тега автоматически обрамляется кавычками.

<cite> используется для того, чтобы выделить источник цитаты, название произведения или автора цитаты.

<p>Words can be like X-rays, if you use them properly—they’ll go through anything. You read and you’re pierced.</p>

<footer>—Aldous Huxley, <cite>Brave New World</cite></footer>

</blockquote>

Постановки

Имеются два класса постановок:

: screenplay — сценарий.

: piece — пьеса,

По структуре они примерно идентичны, внешний вид можно варьировать стилями.

Указание стиля произведения.

Если во включении, то ставится соответствующий класс,

Если целиком произведение, то метаинформация {{screenplay}} {{piece}}

будут назначаться классы в зависимости оть отступов и других признаков

//TD сделать таблицу соответствия классов и тегов отступам

я таблица

Дополнительный признак заголовка сцены в сценарии: заглавные буквы, а в пьесе - части и главы.

Признак ремарки: скобки.

Признак титра - слово ТИТР (TITER)

Ремарка кладется внутрь реплики для того, чтобы можно было менять стиль на компактный.

--- Виды стилей Флаги для стиля отображения постановки указываются в метаинформации или при конвертации в настройках конвертера: : play-classic — сценарий, для фильма по классике моноширинный шрифт. : piece-classic — пьеса, примерно по сценарийным отступам, но с красивыми шрифтами. : piece-compact — суперкомпактное отображение. : piece-column — диалоги в отдельном столбце. {{}} по умолчанию scsreenplay — , а piece — Сценарий можно преобразовать и в одно из представлений пьесы и наоборот.

Спецсимволы

Пропуск текста

<...> заменить на одинарные угловые кавычки и троеточие ‹…› (&lsaquo;…&rsaquo;)

Спецсимволы, которых нет на Клавиатуре

Кавычки-ёлочки «»

« - комбинация Alt + 0171 (на NumLock клавиатуре);

» - комбинация Alt + 0187 (на NumLock клавиатуре).

171

\00AB

U+00AB

aquo

Открывающая левая кавычка «ёлочка»

187

\00BB

U+00BB

aquo

Закрывающая правая кавычка «ёлочка»

‹

8249

\2039

U+2039

saquo

Одинарная открывающая (левая) французская угловая кавычка

›

8250

\203A

U+203A

saquo

…

Тире —

§ (параграф)

многоточие в угловых скобках ‹…›

saquo;…&rsaquo

Не нужно заменять!

…

8230

\2026

U+2026

ellip

Многоточие

Особенности экспорта произведения в html

Чтобы при экспорте markvan-text в html код не интерпретировался браузером, а визуально отображался для читателя, угловые скобки < и > заменяются на < и &gt.

Что делать Если нам необходимо включить html-код в страницу?

а) =[!html]= =[<html>]= позволяет вставлять html-код на страницу как есть без оборачивания в тег code. б) использовать какие-нибудь типа {{ }} или [{ }] или [# #]